home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 25 / AACD 25.iso / AACD / Magazine / Online / QMail / man / cat5 / maildir.0 < prev    next >
Encoding:
Text File  |  1997-09-21  |  7.2 KB  |  199 lines
  1.  
  2.  
  3.  
  4. maildir(5)                                             maildir(5)
  5.  
  6.  
  7. NNAAMMEE
  8.        maildir - directory for incoming mail messages
  9.  
  10. IINNTTRROODDUUCCTTIIOONN
  11.        _m_a_i_l_d_i_r  is  a  structure for directories of incoming mail
  12.        messages.  It solves the reliability problems that  plague
  13.        _m_b_o_x files and _m_h folders.
  14.  
  15. RREELLIIAABBIILLIITTYY IISSSSUUEESS
  16.        A machine may crash while it is delivering a message.  For
  17.        both _m_b_o_x files and _m_h folders this means that the message
  18.        will  be silently truncated.  Even worse: for _m_b_o_x format,
  19.        if the message is truncated in the middle of  a  line,  it
  20.        will  be  silently  joined  to the next message.  The mail
  21.        transport agent will try again later to deliver  the  mes-
  22.        sage,  but  it  is  unacceptable  that a corrupted message
  23.        should show up at all.  In _m_a_i_l_d_i_r, every message is guar-
  24.        anteed complete upon delivery.
  25.  
  26.        A  machine may have two programs simultaneously delivering
  27.        mail to the same user.  The _m_b_o_x and  _m_h  formats  require
  28.        the programs to update a single central file.  If the pro-
  29.        grams do not use some locking mechanism, the central  file
  30.        will  be corrupted.  There are several _m_b_o_x and _m_h locking
  31.        mechanisms, none of which work portably and reliably.   In
  32.        contrast,  in  _m_a_i_l_d_i_r, no locks are ever necessary.  Dif-
  33.        ferent delivery processes never touch the same file.
  34.  
  35.        A user may try to delete messages from his mailbox at  the
  36.        same  moment that the machine delivers a new message.  For
  37.        _m_b_o_x and _m_h formats, the user's mail-reading program  must
  38.        know  what  locking  mechanism  the mail-delivery programs
  39.        use.  In contrast, in _m_a_i_l_d_i_r, any delivered  message  can
  40.        be safely updated or deleted by a mail-reading program.
  41.  
  42.        Many sites use Sun's NNeettwwoorrkk FFaiilluree SSyysstteemm (NFS), presum-
  43.        ably because the operating system vendor  does  not  offer
  44.        anything else.  NFS exacerbates all of the above problems.
  45.        Some NFS implementations don't provide aannyy reliable  lock-
  46.        ing  mechanism.  With _m_b_o_x and _m_h formats, if two machines
  47.        deliver mail to the same user, or if  a  user  reads  mail
  48.        anywhere  except  the delivery machine, the user's mail is
  49.        at risk.  _m_a_i_l_d_i_r works without trouble over NFS.
  50.  
  51. TTHHEE MMAAIILLDDIIRR SSTTRRUUCCTTUURREE
  52.        A directory in _m_a_i_l_d_i_r format  has  three  subdirectories,
  53.        all on the same filesystem: ttmmpp, nneeww, and ccuurr.
  54.  
  55.        Each  file  in nneeww is a newly delivered mail message.  The
  56.        modification time of the file is the delivery date of  the
  57.        message.   The message is delivered _w_i_t_h_o_u_t an extra UUCP-
  58.        style FFrroomm__ line, _w_i_t_h_o_u_t any >>FFrroomm quoting,  and  _w_i_t_h_o_u_t
  59.        an  extra  blank line at the end.  The message is normally
  60.        in RFC 822 format, starting with a RReettuurrnn--PPaatthh line and  a
  61.  
  62.  
  63.  
  64.                                                                 1
  65.  
  66.  
  67.  
  68.  
  69.  
  70. maildir(5)                                             maildir(5)
  71.  
  72.  
  73.        DDeelliivveerreedd--TToo  line,  but it could contain arbitrary binary
  74.        data.  It might not even end with a newline.
  75.  
  76.        Files in ccuurr are just like files in nneeww.  The big  differ-
  77.        ence  is  that  files  in ccuurr are no longer new mail: they
  78.        have been seen by the user's mail-reading program.
  79.  
  80. HHOOWW AA MMEESSSSAAGGEE IISS DDEELLIIVVEERREEDD
  81.        The ttmmpp directory is used to ensure reliable delivery,  as
  82.        discussed here.
  83.  
  84.        A program delivers a mail message in six steps.  First, it
  85.        cchhddiirr(())s to the _m_a_i_l_d_i_r directory.  Second, it ssttaatt(())ss the
  86.        name  ttmmpp//_t_i_m_e_._p_i_d_._h_o_s_t,  where _t_i_m_e is the number of sec-
  87.        onds since the beginning of 1970 GMT, _p_i_d is the program's
  88.        process  ID,  and _h_o_s_t is the host name.  Third, if ssttaatt(())
  89.        returned anything other than ENOENT,  the  program  sleeps
  90.        for two seconds, updates _t_i_m_e, and tries the ssttaatt(()) again,
  91.        a limited number of times.  Fourth,  the  program  creates
  92.        ttmmpp//_t_i_m_e_._p_i_d_._h_o_s_t.  Fifth, the program _N_F_S_-_w_r_i_t_e_s the mes-
  93.        sage to the file.  Sixth, the program lliinnkk(())s the file  to
  94.        nneeww//_t_i_m_e_._p_i_d_._h_o_s_t.   At  that instant the message has been
  95.        successfully delivered.
  96.  
  97.        The delivery program is required to start a 24-hour  timer
  98.        before creating ttmmpp//_t_i_m_e_._p_i_d_._h_o_s_t, and to abort the deliv-
  99.        ery if the timer expires.  Upon error, timeout, or  normal
  100.        completion,  the  delivery program may attempt to uunnlliinnkk(())
  101.        ttmmpp//_t_i_m_e_._p_i_d_._h_o_s_t.
  102.  
  103.        _N_F_S_-_w_r_i_t_i_n_g means (1) as usual,  checking  the  number  of
  104.        bytes returned from each wwrriittee(()) call; (2) calling ffssyynncc(())
  105.        and checking its return value;  (3)  calling  cclloossee(())  and
  106.        checking  its return value.  (Standard NFS implementations
  107.        handle ffssyynncc(()) incorrectly but make up for it  by  abusing
  108.        cclloossee(()).)
  109.  
  110. HHOOWW AA MMEESSSSAAGGEE IISS RREEAADD
  111.        A mail reader operates as follows.
  112.  
  113.        It  looks through the nneeww directory for new messages.  Say
  114.        there is a new message, nneeww//_u_n_i_q_u_e.  The reader may freely
  115.        display  the contents of nneeww//_u_n_i_q_u_e, delete nneeww//_u_n_i_q_u_e, or
  116.        rename     nneeww//_u_n_i_q_u_e     as     ccuurr//_u_n_i_q_u_e_:_i_n_f_o.      See
  117.        hhttttpp::////ppoobbooxx..ccoomm//~~ddjjbb//mmaaiillddiirr..hhttmmll   for  the  meaning  of
  118.        _i_n_f_o.
  119.  
  120.        The reader is also expected to look through the ttmmpp direc-
  121.        tory and to clean up any old files found there.  A file in
  122.        ttmmpp may be safely removed if it has not been  accessed  in
  123.        36 hours.
  124.  
  125.        It is a good idea for readers to skip all filenames in nneeww
  126.        and ccuurr starting with a dot.   Other  than  this,  readers
  127.  
  128.  
  129.  
  130.                                                                 2
  131.  
  132.  
  133.  
  134.  
  135.  
  136. maildir(5)                                             maildir(5)
  137.  
  138.  
  139.        should not attempt to parse filenames.
  140.  
  141. EENNVVIIRROONNMMEENNTT VVAARRIIAABBLLEESS
  142.        Mail  readers  supporting _m_a_i_l_d_i_r use the MMAAIILLDDIIRR environ-
  143.        ment variable as the  name  of  the  user's  primary  mail
  144.        directory.
  145.  
  146. SSEEEE AALLSSOO
  147.        mbox(5), qmail-local(8)
  148.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.                                                                 3
  197.  
  198.  
  199.